Summary

This PR implements a comprehensive, defensive path resolution fix for a critical production bug where filesystem tools (read_file, replace, write_file) fail with a "File not found" error when the model passes a path prefixed with @ (e.g., @policies/new-policies.txt).

Additionally, this PR resolves macOS-specific test failures in EditTool and WriteFileTool caused by path resolution mismatches (due to the /var -> /private/var symlink on macOS), sanitizes file paths by stripping null bytes to prevent potential crash vulnerabilities, and enhances test stability by generating unique session IDs in trackerTools.test.ts.

Furthermore, this PR incorporates several critical security and robustness enhancements requested during code review, including consistent @ prefix stripping, plan-mode boundary enforcement, and test isolation improvements.

Details

We implemented a centralized, defensive path resolution utility and applied targeted, platform-aware fixes to align the test environment with the production path resolution behavior:

1. Defensive Path Resolution (packages/core/src/utils/paths.ts):

   • Implemented resolveDefensiveToolPath to strip leading @ reference prefixes if the literal path does not exist but the stripped path does.
   • Consistent @ Prefix Stripping: Updated the logic to consistently strip the @ prefix when creating new files/directories (unless a literal @-prefixed directory already exists on disk), preventing the accidental creation of literal @-prefixed folders (e.g., @src, @policies).
   • Path Alias Support: Added explicit checks for @/ and @\ prefixes to always strip the @ and leading slashes, ensuring that common path aliases are resolved correctly even when the target directory does not exist yet.
   • Null Byte Sanitization: Sanitizes file paths by stripping any null bytes (\0) at the very beginning of resolveDefensiveToolPath to prevent potential crash vulnerabilities (TypeError) in downstream synchronous file system operations.

2. Tool Integration & Hardening:

   • ReadFileTool (packages/core/src/tools/read-file.ts): Applied resolveDefensiveToolPath in both the constructor and validateToolParamValues.
   • WriteFileTool (packages/core/src/tools/write-file.ts):
     • Applied resolveDefensiveToolPath in the constructor, validateToolParamValues, and getCorrectedFileContent (simplifying and hardening the logic by calling it directly for all paths, including absolute paths).
     • Plan-Mode Boundary Enforcement: Removed the path.isAbsolute check in getCorrectedFileContent to ensure that absolute paths in plan mode do not bypass resolveAndValidatePlanPath, strictly restricting the agent to the plans directory.
     • Plan-Mode Sanitization: Sanitizes null bytes from file paths before resolving the plan path in the constructor, validation, and content correction methods to prevent resolveToRealPath from throwing errors.
   • EditTool (packages/core/src/tools/edit.ts):
     • Applied resolveDefensiveToolPath in the constructor, validateToolParamValues, and getModifyContext.
     • Null Byte Sanitization in Fallbacks: Added explicit null byte sanitization in the absolute path fallback branches (constructor, validation, and context methods) to prevent unsanitized paths from leaking downstream.
     • Plan-Mode Sanitization: Sanitizes null bytes from file paths before resolving the plan path in the constructor, validation, and context methods to prevent resolveToRealPath from throwing errors.
   • Path Corrector (packages/core/src/utils/pathCorrector.ts): Applied resolveDefensiveToolPath at the beginning of correctPath.

3. macOS Test Fixes & Test Isolation:

   • Mock Workspace Context (packages/core/src/test-utils/mockWorkspaceContext.ts): Updated createMockWorkspaceContext to resolve all input directories to their real paths using fs.realpathSync. This ensures that on macOS, any directory starting with /var/... is correctly resolved to /private/var/..., matching the behavior of the production code and fixing 30 failures in edit.test.ts and boundary failures in write-file.test.ts.
   • WriteFileTool Tests (packages/core/src/tools/write-file.test.ts):
     • Test Isolation: Declared rootDir and plansDir without static global initializers and initialized them with unique temporary directories using fs.mkdtempSync inside beforeEach to prevent race conditions and test interference during concurrent test execution.
     • Updated specific test cases to resolve expected paths to their real paths using resolveToRealPath before asserting.
   • EditTool Tests (packages/core/src/tools/edit.test.ts):
     • Resolved tempDir to its real path using fs.realpathSync in beforeEach to ensure all generated paths are fully resolved, fixing all remaining macOS path mismatches.

4. Test Stability:

   • Tracker Tools Tests (packages/core/src/tools/trackerTools.test.ts): Replaced the hardcoded sessionId: 'test-session' with a dynamically generated unique session ID using Math.random() to prevent test session leakage and concurrency issues.

5. Consolidated Test Suite (packages/core/src/tools/at-reference-resolution.test.ts):

   • Created a new consolidated test suite verifying successful path resolution, file updates, new file creation, nested subdirectory creation, path traversal blocking, and symlink loop handling across all three tools.

6. Build Script Robustness (scripts/build.js):

   • Modified the build script to use npx --no-install npm-run-all to force using the locally installed version and bypass registry/network calls, making the build script robust in corporate environments (Corp Airlock).

Related Issues

How to Validate

Step 1: Run the modified test suites on macOS

Run the following commands on a macOS machine to verify that all tests pass successfully:

npx vitest run packages/core/src/tools/edit.test.ts
npx vitest run packages/core/src/tools/write-file.test.ts
npx vitest run packages/core/src/tools/at-reference-resolution.test.ts
npx vitest run packages/core/src/tools/trackerTools.test.ts

Expected Output: All 125+ tests pass successfully with zero failures.

Step 2: Run the test suites on Linux/Windows (Regression Check)

Run the same commands on Linux or Windows to ensure zero regressions:

npx vitest run packages/core/src/tools/write-file.test.ts packages/core/src/tools/at-reference-resolution.test.ts

Expected Output: All 63 tests pass successfully with zero failures.

Step 3: Run linting and type checking

Verify that the codebase remains fully compliant with the project's engineering standards:

npm run lint && npm run typecheck

Expected Output: Zero linting or type-checking errors.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
  • Windows
    • npm run
    • npx
  • Linux
    • npm run
    • npx